
//Copyright 1997-2009 Syrinx Development, Inc.
//This file is part of the Syrinx Web Application Framework (SWAF).
// == BEGIN LICENSE ==
//
// Licensed under the terms of any of the following licenses at your
// choice:
//
//  - GNU General Public License Version 3 or later (the "GPL")
//    http://www.gnu.org/licenses/gpl.html
//
//  - GNU Lesser General Public License Version 3 or later (the "LGPL")
//    http://www.gnu.org/licenses/lgpl.html
//
//  - Mozilla Public License Version 1.1 or later (the "MPL")
//    http://www.mozilla.org/MPL/MPL-1.1.html
//
// == END LICENSE ==
using System;
using Swaf;
using Swaf.Call;
using Swaf.Container;

namespace Swaf.Security
{
	/// <summary>
	/// The Privileges enumeration provides the available privileges that can be 
	/// assigned to resources.  Being an enumeration, the values of each enumeration 
	/// element increase as you go down the list, allowing for equality operators to 
	/// be used to compare privileges.
	/// </summary>
	/// <remarks>
	/// <p>Privileges.None - This enumeration entry has a value of 0 and indicates that there are no privileges defined for the requested resource.
	/// <p>Privileges.Derived - This enumeration entry has a value of 1 and indicates that the privileges to the associated resource should be derived from another resource.  This value is provided predominantly for the MenuElement resource which derives its privileges from the associated target page.</p>
	/// <p>Privileges.Execute - This enumeration entry has a value of 2 and relates specifically to BizRule resources.</p>
	/// <p>Privileges.ReadOnly - This enumeration has a value of 3 and is the minimum privilege for UI resources including pages.</p>
	/// <p>Privileges.AddOnly - This enumeration allows users to create new elements and edit only ones they created..</p>
	/// <p>Privileges.EditOnly - This enumeration has a value of 5 and includes all resources at lower levels.</p>
	/// <p>Privileges.Edit - This enumeration has a value of 5 and includes all resources at lower levels.</p>
	/// <p>Privileges.Add - This enumeration has a value of 6 and includes all resources at lower levels.</p>
	/// <p>Privileges.Delete - This enumeration has a value of 7 and indicates that all privileges are available.</p>
	/// </remarks>
	public enum Privileges
	{
		NotSet = -1,
		None = 0,
		Derived = 1,
		Execute = 2,
		ReadOnly = 3,
		AddOnly = 4,
		EditOnly = 5,
		Edit = 6,
		Add = 7,
		Delete = 8
	}
	/// <summary>
	/// The security principal object represents the primary security element for a user in a 
	/// CSF application.  The ISecurityPrincipal interface provides the methods and properties 
	/// that are common to any implementation of a security principal.  
	/// </summary>
	public interface ISecurityPrincipal : INameAddressSupport
	{
		/// <summary>
		/// The resourceSets property is read-only and returns an INameAddressSupport instance 
		/// containing named resourceSet objects.  These resourceSet objects should be copied 
		/// from the master list of resourceSet objects exposed via the resourceSets property 
		/// of the SecurityManager class when an instance of a class realizing this interface 
		/// is created.
		/// </summary>
		INameAddressSupport resourceSets{get;}
		
		/// <summary>
		/// The roles property is read-only and returns an INameAddressSupport instance 
		/// containing named role objects.  Classes realizing this interface should populate 
		/// this collection during class initialization using the rolesCall ICall instance.
		/// </summary>
		INameAddressSupport roles{get;}
		
		/// <summary>
		/// The rolesCall property is read-only and returns a reference to the ICall instance 
		/// used to retrieve the list of roles for a given principal.  The value for this 
		/// property should be set in the constructor for the realizing Security Principal 
		/// class.  The ICall instance will be created by the SecurityManager class by using 
		/// the value defined in the RolesCall configuration element.
		/// </summary>
		ICall rolesCall{get;}
		
		/// <summary>
		/// The isUserInRole method returns a Boolean value indicating whether the current 
		/// principal has been assigned to the requested role.  This method takes a single 
		/// string parameter indicating the name of the requested role.
		/// </summary>
		/// <param name="roleName">The name of the role to be tested for.</param>
		/// <returns></returns>
		bool isUserInRole(string roleName);
		
		/// <summary>
		/// The getPrivilege method returns a Privilege enumeration value for the requested 
		/// resource for the current principal.  This method takes a single string parameter 
		/// indicating the name of the resource for which privileges are being requested.  
		/// Because resources are stored in ResourceSets, the resource name provided must be 
		/// prefixed with the name of the containing resource set.  This method supports deep 
		/// name address syntax.   If the resource being requested does not exist, this method 
		/// should return Privileges.None.
		/// </summary>
		/// <param name="resourceName">The name of the resource being tested for.</param>
		/// <returns>The effective Privilege for the current user</returns>
		Privileges getPrivilege(string resourceName);
		Privileges getPrivilege(string resourceName, bool useDefaultIfNeeded);
		
		/// <summary>
		/// The hasPrivilege method returns a Boolean indicating whether the current principal 
		/// has any privileges for the requested resource.  This method is provided for 
		/// scenarios where you are only concerned with whether the user has any privilege 
		/// greater than None but don�t really care what the specific privilege is.
		/// </summary>
		/// <param name="resourceName">The name of the resource being tested for.</param>
		/// <returns></returns>
		bool hasPrivilege(string resourceName);
		
		/// <summary>
		/// The userName property is read-only and returns a string indicating the identifier 
		/// for the current logged in user.  The underlying value should be set in the 
		/// constructor.
		/// </summary>
		string userName{get;}
		
		/// <summary>
		/// The additionalInfo property returns an INameAddressSupport class instance (FlexiMap) 
		/// with elements containing relevant, application specific security information.
		/// </summary>
		INameAddressSupport additionalInfo{get;}
		
		/// <summary>
		/// The assert method provides a security assertion mechanism.  This method takes two 
		/// parameters: a string indicating the name of the requested resource and a Privileges 
		/// enumeration entry indicating the minimum privilege required for the requested 
		/// resource.  If the current principal does not have the minimum privilege for the 
		/// requested resource, an AccessDeniedException should be thrown.
		/// </summary>
		/// <param name="resourceName">The name of the resource being tested for.</param>
		/// <param name="minPrivilege">The sought Privilige</param>
		void assert(string resourceName, Privileges minPrivilege);

		/// <summary>
		/// The read-only instanceId property returns a guid which uniquely identifies a security 
		/// principal within the system.  This property is used to compare to principals.
		/// </summary>
		string instanceId{get;}
		bool deepCloneResourceSets{get;set;}
}
}
